This folder contains the latest pre-release version of GSBug & Debugging
Tools. These tools are useful with or without either the APW or ORCA
development environments (i.e.: if you're using Merlin, Micol, TML, MPW IIGS,
or any other development environment to write Apple IIGS software, then these
tools (especially GSBug) will be VERY useful in finding bugs in the software
you're developing.
These tools are a fully copyrighted work of Apple Computer, Inc and may NOT be
redistributed. They are being provided to you for your own use as our way of
saying, "Thanks for developing for the Apple IIGS". All Rights Reserved.
Futher information on using GSBug itself can be found in the "GSBug.Tutorial"
file in the same folder as this "Read.Me" file. Details on how to use the new
"calls" that have been added to GSBug can be found in the "GSBug.Specs" file
which is also in the same folder as this "Read.Me" file. Reading those two
files will explain a LOT of things to you. The tutorial is especially useful
if you do not have the manual (or you have the manual, but never bothered to
read it).
The tutorial and specs files will only teach you the basics, there is a LOT
more that can be done with GSBug, but you'll need the manual to be able to
tap into them. The 140 page manual for GSBug & Debugging Tools contains full
details on how to use these tools. Those of you without this manual can get
one by contacting APDA at 1-800-282-2732 (in the U.S.), 1-800-637-0029 (in
Canada), and 408-562-3910 (International). The part number for this package
is "A0037LL/A" and the price is thirty dollars ($30). You no longer need to be a member of APDA to be able to order this product, contact APDA for full details.
GSBug best supports debugging of 16-bit software. Recent changes made to it
provide minimal functionality for debugging 8-bit software. Please read the
"GSBug.Specs" file for details.
ONLY the INIT version of GSBug is being provided. The application version is
most likely going to "go away" in the future. Instead, we'll provide an easy
way for you to install and remove the INIT version on the fly. Currently, you
can remove the INIT version after booting by simply entering the debugger (the
tutorial file tells you how) and typing "UNLOAD", then pressing RETURN. This
removes the debugger. If your application crashed into the debugger and you
unload the debugger, your application will still be crashed (but into the
monitor now that GSBug is gone). If your application is NOT crashed (i.e.:
you entered the debugger by pressing the key sequence that drops you in
safely), then unloading GSBug will resume operation of your application as
though nothing happened (actually, plenty happened - GSBug was removed from
memory and you can't drop into it any more because it's gone).
Having only the INIT version solves several problems you would have
encountered had you tried using the application version of GSBug along with an
application that uses resources. GSBug is technically the "current"
application, so calls to the Resource Manager would actually look in GSBug's
resource fork (which is non-existant) instead of your application's. The INIT
version prevents this conflict (and several other similar ones caused by
confusion of which app is the "current" one).
Directions for installing theses tools are below:
GSBug & Debugging Tools installation:
- copy the files in the "GSBug/System.Setup/" folder
to your boot disk's System.Setup folder (full path would be:
"*/System/System.Setup/"). This will provide you with the INIT version
of GSBug the next time you boot your computer from the disk you just
installed onto. It will also provide you with the templates for toolbox
data structures (such as grafPorts, windows, menu bars, etc).
Information on using the templates can be found in the "Templates.Info"
file. General info on using templates of your own with GSBug can be
found in the GSBug Reference manual (available from APDA).
- copy the desk accessories in the "GSBug/Desk.Accs/"
folder to your boot disk's Desk.Accs folder (full path would be:
"*/System/Desk.Accs/"). This will provide you with additional debugging
tools such as loader/dumper, memory mangler, scrambler, and snooper. You
must reboot from the disk you just installed onto in order for those desk
accessories to show up.
- copy the Exerciser application to where ever you normally install your
applications. It doesn't really care what folder it lives in. There is
a desk accessory version of the Exerciser, so you don't HAVE to use the
application version if you don't want to.
Double check your */System/System.Setup folder to be certain that you have
ONLY one copy of the GSBug INIT file. The old name for this file is
"GSBug.INIT" and some pre-release versions went out with the INIT named
"debug.INIT". Having two copies of GSBug will cause nasty things to happen
since both copies would be trying to do the same thing. One GSBug is all you
need.
DISCLAIMER OF WARRANTY
THE SOFTWARE IS PROVIDED "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
WITH RESPECT TO ITS MERCHANTABILITY OR ITS FITNESS
FOR ANY PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU (AND
NOT APPLE OR AN APPLE AUTHORIZED REPRESENTATIVE)
ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
Apple does not warrant that the functions
contained in the Software will meet your requirements
or that the operation of the Software will be
uninterrupted or error free or that defects in the
Software will be corrected.
SOME STATES DO NOT ALLOW THE EXCLUSION
OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY
NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC
